3D Graphics Programming with QuickDraw 3D 1.5.4

Handling Viewer Events

Viewer objects support several routines for handling events that occur in a viewer pane. The 3D Viewer provides two different event handling models: closed-loop event handling and open-loop event handling. You should decide which model best fits your needs and use it exclusively.

Q3ViewerEvent

You can use the Q3ViewerEvent function to give the 3D Viewer an opportunity to handle Macintosh events involving a viewer object. This function has no equivalent in the Windows environment.



 
Boolean Q3ViewerEvent (

                     TQ3ViewerObject    theViewer,

                     EventRecord        *evt);

theViewer: A viewer object.
evt: An event record.

DESCRIPTION

The Q3ViewerEvent function returns, as its function result, a Boolean value that indicates whether the event specified by the evt parameter relates to the viewer object specified by the theViewer parameter and was successfully handled (TRUE ) or whether that event either does not relate to that viewer object or could not be handled by the 3D Viewer (FALSE ). The evt parameter is a pointer to an event record, which you usually obtain by calling the Event Manager function WaitNextEvent .

Q3ViewerEvent can handle most of the events relating to a viewer object. For example, it handles all user events relating to the controller strip displayed with a viewer object. For information on how to handle editing commands in a viewer pane, see "Handling Edit Commands" .

SPECIAL CONSIDERATIONS

You should call Q3ViewerEvent in your main event loop to give the 3D Viewer an opportunity to handle events in a window that relate to a viewer object.

The Q3ViewerEvent function implements a closed-loop event handling model and should therefore not be used in conjunction with functions that implement an open-loop event handling model (namely, Q3ViewerMouseDown , Q3ViewerMouseUp , Q3ViewerContinueTracking , and Q3ViewerHandleKeyEvent ).

Q3ViewerMouseDown

You can use the Q3ViewerMouseDown function to notify the 3D Viewer that a mouse-down event has occurred.

MAC OS VERSION



 
Boolean Q3ViewerMouseDown (

                     TQ3ViewerObject    theViewer,

                     long               x,

                     long               y);

WINDOWS VERSION



 
BOOL Q3WinViewerMouseDown (

                     TQ3ViewerObject    viewer,

                     long               x,

                     long               y );

PARAMETERS

theViewer: A viewer object.
x: The horizontal position, in global coordinates, of the mouse at the time the mouse-down event occurred.
y: The vertical position, in global coordinates, of the mouse at the time the mouse-down event occurred.

DESCRIPTION

The Q3ViewerMouseDown function informs the 3D Viewer that a mouse-down event has occurred at the screen location specified by the x and y parameters in the pane associated with the viewer specified by the theViewer parameter. Q3ViewerMouseDown returns a Boolean value indicating whether the 3D Viewer handled the event (TRUE ) or not (FALSE ).

SPECIAL CONSIDERATIONS

The Q3ViewerMouseDown function is available only in versions 1.1 and later of the 3D Viewer.

The Q3ViewerMouseDown function implements an open-loop event handling model and should therefore not be used in conjunction with Q3ViewerEvent , which implements a closed-loop event handling model.

Q3ViewerMouseUp

You can use the Q3ViewerMouseUp function to notify the 3D Viewer that a mouse-up event has occurred.

MAC OS VERSION



 
Boolean Q3ViewerMouseUp (

                     TQ3ViewerObject    theViewer,

                     long               x,

                     long               y);

WINDOWS VERSION



 
BOOL Q3WinViewerMouseUp (

                     TQ3ViewerObject    viewer,

                     long               x,

                     long               y );

PARAMETERS

theViewer: A viewer object.
x: The horizontal position, in global coordinates, of the mouse at the time the mouse-up event occurred.
y: The vertical position, in global coordinates, of the mouse at the time the mouse-up event occurred.

DESCRIPTION

The Q3ViewerMouseUp function informs the 3D Viewer that a mouse-up event has occurred at the screen location specified by the x and y parameters in the pane associated with the viewer specified by the theViewer parameter. Q3ViewerMouseUp returns a Boolean value indicating whether the 3D Viewer handled the event (TRUE ) or not (FALSE ).

SPECIAL CONSIDERATIONS

The Q3ViewerMouseUp function is available only in versions 1.1 and later of the 3D Viewer.

The Q3ViewerMouseUp function implements an open-loop event handling model and should therefore not be used in conjunction with Q3ViewerEvent , which implements a closed-loop event handling model.

Q3ViewerContinueTracking

You can use the Q3ViewerContinueTracking function to notify the 3D Viewer that an event has occurred and the mouse is still down.

MAC OS VERSION



 
Boolean Q3ViewerContinueTracking (

                     TQ3ViewerObject    theViewer,

                     long               x,

                     long               y);

WINDOWS VERSION



 
BOOL Q3WinViewerContinueTracking (

                     TQ3ViewerObject    viewer,

                     long               x,

                     long               y );

PARAMETERS

theViewer: A viewer object.
x: The horizontal position, in global coordinates, of the mouse at the current time.
y: The vertical position, in global coordinates, of the mouse at the current time.

DESCRIPTION

The Q3ViewerContinueTracking function informs the 3D Viewer that an event has occurred at the screen location specified by the x and y parameters in the pane associated with the viewer specified by the theViewer parameter. Q3ViewerContinueTracking returns a Boolean value indicating whether the 3D Viewer handled the event (TRUE ) or not (FALSE ).

SPECIAL CONSIDERATIONS

The Q3ViewerContinueTracking function is available only in versions 1.1 and later of the 3D Viewer.

The Q3ViewerContinueTracking function implements an open-loop event handling model and should therefore not be used in conjunction with Q3ViewerEvent , which implements a closed-loop event handling model.

Q3ViewerHandleKeyEvent

You can use the Q3ViewerHandleKeyEvent function to give the 3D Viewer an opportunity to handle Macintosh keyboard events involving a viewer object. This function has no equivalent in the Windows environment.



 
Boolean Q3ViewerHandleKeyEvent (

                     TQ3ViewerObject theViewer, 

                     EventRecord *evt);

theViewer: A viewer object.
evt: An event record.

DESCRIPTION

The Q3ViewerHandleKeyEvent function returns, as its function result, a Boolean value that indicates whether the keyboard event specified by the evt parameter relates to the viewer object specified by the theViewer parameter and was successfully handled (TRUE ) or whether that event either does not relate to that viewer object or could not be handled by the 3D Viewer (FALSE ). The evt parameter is a pointer to an event record, which you usually obtain by calling the Event Manager function WaitNextEvent . This event should be a key-up, key-down, or auto-key event.

SPECIAL CONSIDERATIONS

The Q3ViewerHandleKeyEvent function is available only in versions 1.1 and later of the 3D Viewer.

The Q3ViewerHandleKeyEvent function implements an open-loop event handling model and should therefore not be used in conjunction with Q3ViewerEvent , which implements a closed-loop event handling model.